<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libcoap: coap_recovery(3)</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">libcoap<span id="projectnumber">&#160;4.2.0</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.8 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('man_coap_recovery.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">coap_recovery(3)</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>coap_recovery</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /></head><body><div xml:lang="en" class="refentry" lang="en"><a id="id1337"></a><div class="titlepage"></div><div class="refnamediv"><h2>NAME</h2><p>coap_recovery, coap_session_set_max_retransmit, coap_session_set_ack_timeout, coap_session_set_ack_random_factor, coap_session_get_max_transmit, coap_session_get_ack_timeout, coap_session_get_ack_random_factor, coap_debug_set_packet_loss — Work with CoAP packet transmissions</p></div><div class="refsynopsisdiv"><a id="_synopsis"></a><h2>SYNOPSIS</h2><p><span class="strong"><strong>#include &lt;coap2/coap.h&gt;</strong></span></p><p><span class="strong"><strong>void coap_session_set_max_retransmit(coap_session_t *<span class="emphasis"><em>session</em></span>,
unsigned int <span class="emphasis"><em>value</em></span>)</strong></span>;</p><p><span class="strong"><strong>void coap_session_set_ack_timeout(coap_session_t *<span class="emphasis"><em>session</em></span>,
coap_fixed_point_t <span class="emphasis"><em>value</em></span>)</strong></span>;</p><p><span class="strong"><strong>void coap_session_set_ack_random_factor(coap_session_t *<span class="emphasis"><em>session</em></span>,
coap_fixed_point_t <span class="emphasis"><em>value</em></span>)</strong></span>;</p><p><span class="strong"><strong>unsigned int coap_session_get_max_transmit(coap_session_t *<span class="emphasis"><em>session</em></span>)</strong></span>;</p><p><span class="strong"><strong>coap_fixed_point_t coap_session_get_ack_timeout(coap_session_t *<span class="emphasis"><em>session</em></span>)</strong></span>;</p><p><span class="strong"><strong>coap_fixed_point_t coap_session_get_ack_random_factor(coap_session_t
*<span class="emphasis"><em>session</em></span>)</strong></span>;</p><p><span class="strong"><strong>int coap_debug_set_packet_loss(const char *<span class="emphasis"><em>loss_level</em></span>)</strong></span>;</p><p>Link with <span class="strong"><strong>-lcoap-2</strong></span>, <span class="strong"><strong>-lcoap-2-gnutls</strong></span>,
<span class="strong"><strong>-lcoap-2-openssl</strong></span> or
<span class="strong"><strong>-lcoap-2-tinydtls</strong></span> depending on your (D)TLS library
type.</p></div><div class="refsect1"><a id="_description"></a><h2>DESCRIPTION</h2><p>For CoAP Confirmable messages, it is possible to define the retry counts,
repeat rate etc. for error recovery.  Further information can be found in
"RFC7272: 4.2. Messages Transmitted Reliably".</p><p>It is not recommended that the suggested default setting are changed, but
there may be some special requirements that need different values and the
consequences of changing these values is fully understood.</p><p>Changing the default values for multicast packets is not supported.</p><p>Some of the parameters or return values are in fixed point format as defined
by the coap_fixed_point_t structure as below</p><pre class="screen">typedef struct coap_fixed_point_t {
  uint16_t integer_part;    /* Integer part of fixed point variable */
  uint16_t fractional_part; /* Fractional part of fixed point variable
                               1/1000 (3 points) precision */
} coap_fixed_point_t;</pre><p>The CoAP message retry rules are (with the default values to compute the time)</p><pre class="screen">1st retransmit after 1 * ack_timeout * ack_random factor (3 seconds)
2nd retransmit after 2 * ack_timeout * ack_random factor (6 seconds)
3rd retransmit after 3 * ack_timeout * ack_random factor (12 seconds)
4th retransmit after 4 * ack_timeout * ack_random factor (24 seconds)
5th retransmit after 5 * ack_timeout * ack_random factor (48 seconds)

As max_transmit (by default) is 4, then the 5th retransmit does not get sent,
but at that point COAP_NACK_TOO_MANY_RETRIES gets raised in the nack_handler
(if defined). Note that the sum of the seconds is 93 matching RFC7252.</pre><p>It should be noted that these retries are separate from the DTLS or TLS
encrypted session setup retry timeouts. For DTLS, the initial requesting
packet will get sent max_retransmit times before reporting failure.
For TLS the initial TCP connection will timeout before reporting failure.</p><p>It is also possible to set up packet losses, for both confirmable, and
non-confirmable messages.  This can be used for stress testing packet
transmission recovery as well as application handling of lossy networks.</p><p>The <span class="strong"><strong>coap_session_set_max_retransmit</strong></span>() function updates the <span class="emphasis"><em>session</em></span> maximum
retransmit count with the new <span class="emphasis"><em>value</em></span>.  The default value is 4.</p><p>The <span class="strong"><strong>coap_session_set_ack_timeout</strong></span>() function updates the <span class="emphasis"><em>session</em></span> initial
ack or response timeout with the new <span class="emphasis"><em>value</em></span>.  The default value is 2.0.</p><p>The <span class="strong"><strong>coap_session_set_ack_random_factor</strong></span>() function updates the <span class="emphasis"><em>session</em></span> ack
random wait factor, used to randomize re-transmissions, with the new <span class="emphasis"><em>value</em></span>.
The default value is 1.5.</p><p>The <span class="strong"><strong>coap_session_get_max_retransmit</strong></span>() function returns the current <span class="emphasis"><em>session</em></span>
maximum retransmit count.</p><p>The <span class="strong"><strong>coap_session_get_ack_timeout</strong></span>() function returns the current <span class="emphasis"><em>session</em></span>
initial ack or response timeout.</p><p>The <span class="strong"><strong>coap_session_get_ack_random_factor</strong></span>() function returns the current
<span class="emphasis"><em>session</em></span> ack random wait factor.</p><p>The <span class="strong"><strong>coap_debug_set_packet_loss</strong></span>() function is uses to set the packet loss
levels as defined in <span class="emphasis"><em>loss_level</em></span>.  <span class="emphasis"><em>loss_level</em></span> can be set as a percentage
from "0%" to "100%".
Alternatively, it is possible to specify which packets of a packet sequence
are dropped.  A definition of "1,5-9,11-20,101" means that packets 1, 5
through 9, 11 through 20 and 101 will get dropped. A maximum of 10 different
packet sets is supported.  The packet count is reset to 0 when
coap_debug_set_packet_loss() is called.
To remove any packet losses, set the <span class="emphasis"><em>loss_level</em></span> to "0%".</p></div><div class="refsect1"><a id="_return_values"></a><h2>RETURN VALUES</h2><p><span class="strong"><strong>coap_session_get_max_retransmit</strong></span>(), <span class="strong"><strong>coap_session_get_ack_timeout</strong></span>() and
<span class="strong"><strong>coap_session_get_ack_random_factor</strong></span>() return their respective current values.</p><p><span class="strong"><strong>coap_debug_set_packet_loss</strong></span>() returns 0 if <span class="emphasis"><em>loss_level</em></span> does not parse
correctly, otherwise 1 if successful.</p></div><div class="refsect1"><a id="_testing"></a><h2>TESTING</h2><p>The libcoap recovery/re-transmit logic will only work for confirmable requests.</p><p>To see what is happening (other than by sniffing the network traffic), the
logging level needs to be set to LOG_DEBUG in the client by using
coap_set_log_level(LOG_DEBUG) and coap_dtls_set_log_level(LOG_DEBUG).</p><p>The client needs to be sending confirmable requests during the test.</p><p>The server can either be stopped, or if packet loss levels are set to 100% by
using coap_debug_set_packet_loss("100%") when receiving the client requests.</p><p><span class="strong"><strong>NOTE:</strong></span> If the server end of the connection is returning ICMP unreachable packets
after being turned off, you will get a debug message of the form
"coap_network_read: unreachable", so libcoap will stop doing the retries.  If
this is the case, then you need to make use of (on the server)
coap_debug_set_packet_loss("100%") or put in some packet filtering to drop the
packets.</p><p>The client should then restart transmitting the requests based on the
ack_timeout, ack_random_factor and max_retransmit values.  The client’s
nack_handler will get called with COAP_NACK_TOO_MANY_RETRIES when the
confirmable request cannot be successfully transmitted.</p></div><div class="refsect1"><a id="_further_information"></a><h2>FURTHER INFORMATION</h2><p>See "RFC7252: The Constrained Application Protocol (CoAP)" for further
information.</p></div><div class="refsect1"><a id="_bugs"></a><h2>BUGS</h2><p>Please report bugs on the mailing list for libcoap:
<a class="ulink" href="mailto:libcoap-developers@lists.sourceforge.net" target="_top">libcoap-developers@lists.sourceforge.net</a></p></div><div class="refsect1"><a id="_authors"></a><h2>AUTHORS</h2><p>The libcoap project &lt;<a class="ulink" href="mailto:libcoap-developers@lists.sourceforge.net" target="_top">libcoap-developers@lists.sourceforge.net</a>&gt;</p></div></div></body></html> coap_recovery(3)</p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Fri Dec 27 2024 09:57:44 for libcoap by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.8 </li>
  </ul>
</div>
</body>
</html>
